[[tags: manual]]
[[toc:]]

== Unit eval

This unit has support for evaluation and macro-handling. This unit is used
by default, unless the program is compiled with the {{-explicit-use}}
option.

=== Loading code

==== load

<procedure>(load FILE [EVALPROC])</procedure>

Loads and evaluates expressions from the given source file, which may
be either a string or an input port.  Each expression read is passed to
{{EVALPROC}} (which defaults to {{eval}}).  On platforms that
support it (currently native Windows, Linux ELF and Solaris), {{load}} can be used
to load compiled programs:

 % cat x.scm
 (define (hello) (print "Hello!"))
 % csc -s x.scm
 % csi -q
 #;1> (load "x.so")
 ; loading x.so ...
 #;2> (hello)
 Hello!
 #;3>

The second argument to {{load}} is ignored when loading compiled
code. 
If source code is loaded from a port, then that port is closed after
all expressions have been read.

Compiled code can be re-loaded, but care has to be taken, if code
from the replaced dynamically loaded module is still executing (i.e.
if an active continuation refers to compiled code in the old module).

Support for reloading compiled code dynamically is still experimental.

==== load-relative

<procedure>(load-relative FILE [EVALPROC])</procedure>

Similar to {{load}}, but loads {{FILE}} relative to the path
of the currently loaded file.

==== load-noisily

<procedure>(load-noisily FILE #!key EVALUATOR TIME PRINTER)</procedure>

As {{load}} but the result(s) of each evaluated toplevel-expression
is written to standard output. If {{EVALUATOR}} is given and not {{#f}},
then each expression is evaluated by calling this argument with the read
expression as argument. If {{TIME}} is given and not false, then
the execution time of each expression is shown (as with the {{time}} macro).
If {{PRINTER}} is given and not false, then each expression is
printed before evaluation by applying the expression to the value of this
argument, which should be a one-argument procedure.

See also the [[http://chicken.wiki.br/Parameters#load-verbose|load-verbose]] parameter.
==== load-library

<procedure>(load-library UNIT [LIBRARYFILE])</procedure>

On platforms that support dynamic loading, {{load-library}} loads
the compiled library unit {{UNIT}} (which should be a symbol). If the
string {{LIBRARYFILE}} is given, then the given shared library will
be loaded and the toplevel code of the contained unit will be executed.
If no {{LIBRARYFILE}} argument is given, then the following libraries
are checked for the required unit:

* a file named ''{{<UNIT>.so}}''
* the files given in the parameter {{dynamic-load-libraries}}

If the unit is not found, an error is signaled.  When the library unit
can be successfully loaded, a feature-identifier named {{UNIT}}
is registered. If the feature is already registered before loading,
the {{load-library}} does nothing.

==== set-dynamic-load-mode!

<procedure>(set-dynamic-load-mode! MODELIST)</procedure>

On systems that support dynamic loading of compiled code via the {{dlopen(3)}}
interface (for example Linux and Solaris), some options can be specified to
fine-tune the behaviour of the dynamic linker. {{MODE}} should be a list of
symbols (or a single symbol) taken from the following set:

; {{local}} : If {{local}} is given, then any C/C++ symbols defined in the dynamically loaded file are not available for subsequently loaded files and libraries. Use this if you have linked foreign code into your dynamically loadable file and if you don't want to export them (for example because you want to load another file that defines the same symbols).
; {{global}} : The default is {{global}}, which means all C/C++ symbols are available to code loaded at a later stage.
; {{now}} : If {{now}} is specified, all symbols are resolved immediately.
; {{lazy}} : Unresolved symbols are resolved as code from the file is executed. This is the default. 

Note that this procedure does not control the way Scheme variables are handled -
this facility is mainly of interest when accessing foreign code.


=== Read-eval-print loop

==== repl

<procedure>(repl)</procedure>

Start a new read-eval-print loop. Sets the {{reset-handler}} so that
any invocation of {{reset}} restarts the read-eval-print loop. Also
changes the current exception-handler to display a message, write
any arguments to the value of {{(current-error-port)}} and reset.


=== Loading extension libraries

This functionality is only available on platforms that support dynamic
loading of compiled code. Currently Linux, BSD, Solaris, Windows (with Cygwin) and HP/UX are supported.

==== repository-path

<parameter>repository-path</parameter>

Contains a string naming the path to the extension repository, which defaults to
either the value of the environment variable {{CHICKEN_REPOSITORY}}
or the default library path
(usually {{/usr/local/lib/chicken}} on UNIX systems).

==== extension-information

<procedure>(extension-information ID)</procedure>

If an extension with the name {{ID}} is installed and if it has a setup-information
list registered in the extension repository, then the info-list is returned. Otherwise
{{extension-information}} returns {{#f}}.

==== provide

<procedure>(provide ID ...)</procedure>

Registers the extension IDs {{ID ...}} as loaded. This is mainly
intended to provide aliases for certain extension identifiers.

==== provided?

<procedure>(provided? ID ...)</procedure>

Returns {{#t}} if the extension with the IDs {{ID ...}}
are currently loaded, or {{#f}} otherwise.

==== require

<procedure>(require ID ...)</procedure>

If the extension library {{ID}} is not already loaded into the
system, then {{require}} will lookup the location of the shared
extension library and load it. If {{ID}} names a library-unit of
the base system, then it is loaded via {{load-library}}.  If no
extension library is available for the given ID, then an attempt is
made to load the file {{ID.so}} or {{ID.scm}} (in that order)
from one of the following locations:

* the current include path, which defaults to the pathnames given in {{CHICKEN_INCLUDE_PATH}}.
* the current directory

{{ID}} should be a string or a symbol.

=== System information

==== chicken-home

<procedure>(chicken-home)</procedure>

Returns a string given the installation directory (usually {{/usr/local/share/chicken}} on UNIX-like systems).
As a last option,
if the environment variable {{CHICKEN_PREFIX}} is set, then {{chicken-home}} will return
{{$CHICKEN_PREFIX/share}}.


=== Eval

==== eval

<procedure>(eval EXP [ENVIRONMENT])</procedure>

Evaluates {{EXP}} and returns the result of the evaluation. The second argument is optional
and defaults to the value of {{(interaction-environment)}}.

---
Previous: [[Unit library]]

Next: [[Unit expand]]
